home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1999 March / EnigmA AMIGA RUN 35 (1999)(G.R. Edizioni)(IT)[!][issue 1999-03].iso / earcd / devel / vbcc-ppc / vbccppc.readme
Text File  |  1999-01-01  |  15KB  |  518 lines
  1. Short:    free optimizing ANSI C compiler (PPC/ELF)
  2. Uploader: volker@vb.franken.de (Volker Barthelmann)
  3. Author:   volker@vb.franken.de (Volker Barthelmann)
  4. Type:     dev/c
  5. Version:  0.7
  6. Replaces: dev/c/vbcc.lha
  7.  
  8. vbcc - portable ANSI C compiler (c) in 1995-99 by Volker Barthelmann
  9.  
  10.  
  11. INTRODUCTION
  12.  
  13.     vbcc is a free portable and retargetable ANSI C compiler.
  14.  
  15.     This archive contains the compiler, preprocessor, assembler, linker,
  16.     frontend, message browser, startup codes, C-libraries, amiga.lib
  17.     replacements as well as several other tools for PPC/ELF.
  18.  
  19.     This gives you a complete system that allows to develop programs in
  20.     ANSI C as well as Amiga-specific programs (provided you obtain the
  21.     OS-includes) running on PPC/ELF.
  22.  
  23.     All major parts of this distribution (including compiler, preprocessor,
  24.     libraries etc.) have been compiled/assembled with this system and
  25.     apart from the OS-includes everything needed to rebuilt vbcc,
  26.     the libraries and many of the other programs is contained in this
  27.     archive and the corresponding source archive.
  28.  
  29.     Note that the programs in this archive all run on the 68k. There is
  30.     another archive which contains compilers that run on the PPC.
  31.  
  32.  
  33. FEATURES
  34.  
  35.     vbcc..
  36.  
  37.     - comes with source
  38.  
  39.     - is free
  40.  
  41.     - is portable and retargetable
  42.  
  43.     - comes with a global optimizer that can e.g. do global common
  44.       subexpression elimination, constant propagation, function inlining
  45.       and several other optimizations (but is not yet finished and may
  46.       have some bugs)
  47.  
  48.     - should be ANSI compliant
  49.  
  50.     - can generate code that runs on a plain 68000 CPU
  51.  
  52.     - can generate code optimized for 020/030, 040 or 060
  53.  
  54.     - can generate code that uses the 68881/2, 68040/060 FPUs directly
  55.       and comes with appropriate math-libraries
  56.  
  57.     - can generate code that runs on PowerUp-boards
  58.  
  59.     - generates standard Amiga-68k-objects, PPC-ELF-objects or
  60.       WarpOS-EHF-objects
  61.  
  62.     - does not need too much memory
  63.  
  64.     - comes with a message browser
  65.  
  66.     - comes with a config program
  67.  
  68.     - offers a lot of error/warning messages that can be turned on/off
  69.       separately
  70.  
  71.  
  72. WHAT'S NEW
  73.  
  74.     Some changes since the last release:
  75.  
  76.     - bug fixes
  77.  
  78.     - new optimizations
  79.  
  80.     - much improved libaries
  81.  
  82.     - use of Frank Wille's linker vlink
  83.  
  84.     - support for PPC/WarpOS
  85.  
  86.     - support for small data for PPC/ELF and PPC/WarpOS
  87.  
  88.     - support for __saveds (68k, PPC/ELF and PPC/WarpOS)
  89.  
  90.     - support for __far (68k, PPC/EFL and PPC/WarpOS)
  91.  
  92.     - support for __chip (68k and PPC/WarpOS)
  93.  
  94.     - support for auto opening of libraries (68k, PPC/ELF and PPC/WarpOS)
  95.  
  96.     - cleaned up distributions for all three Amiga targets
  97.  
  98.     - checking for unresolved symbols for PPC/ELF
  99.  
  100.     - scheduler for PPC (ELF and WarpOS)
  101.  
  102.  
  103. REQUIREMENTS
  104.  
  105.     To use vbcc you need:
  106.  
  107.     - an Amiga with OS 2.0 or higher
  108.  
  109.     - enough RAM (it is possible to translate small programs with 1MB, but
  110.       for larger programs much more will be needed)
  111.  
  112.     Stuff that is not needed, but may be very useful:
  113.  
  114.     - harddisk
  115.  
  116.     - editor
  117.  
  118.     - make, touch etc.
  119.  
  120.     - the Amiga OS-includes (they can be found on certain CDs)
  121.  
  122.     - pipe-command (to use the message browser)
  123.  
  124.     Also you should know how to use the shell and you should know ANSI C
  125.     (if you need a book I recommend (like everyone) "The C Programming
  126.     Language, Second Edition, ANSI C" by Kernighan and Ritchie).
  127.  
  128.  
  129. LEGAL
  130.  
  131.     Note that this distribution contains several programs, libraries etc.
  132.     that are from different authors and are under different legal status.
  133.     So always read the corresponding doc/guide-file to find out under
  134.     what conditions a certain file may be used, distributed etc.
  135.  
  136.     For the most part you can assume that you may use everything for
  137.     non-commercial purposes and may distribute the unchanged archive
  138.     in whole.
  139.  
  140.     Changing any parts from this archive, distributing parts of it or
  141.     using it commercially might be legal for certain parts, but illegal
  142.     for others, so read all docs carefully before doing any of the above.
  143.  
  144.     This archive contains code written by (this list may be incomplete):
  145.  
  146.     Volker Barthelmann, Frank Wille, Thorsten Schaaps, Dennis Ritchie,
  147.     Matthias Fleischer, Gunther Nikl, Mike Schwartz, Kasper Graversen,
  148.     Johnny Tevessen
  149.  
  150.     However, if you have any comments/problems etc. with anything, please
  151.     do not bother them, but write to me (volker@vb.franken.de) first.
  152.     Exceptions are the parts by Kasper Graversen.
  153.  
  154.  
  155. INSTALLATION/TUTORIAL
  156.  
  157.     [Names of directories, binaries or assigns have changed since earlier
  158.      versions as have config-files. So users of earlier versions should
  159.      read this again and do a complete re-install to avoid problems.]
  160.  
  161.     The first step (which you probably already did) is to extract the
  162.     entire archive (take care to preserve the file attributes). If you
  163.     have several archives of the vbcc distribution you can just extract
  164.     them all to the same place.
  165.  
  166.     The distributed programs are for the most part only usable from a shell.
  167.  
  168.     To use vbcc the following steps are necessary:
  169.  
  170.     1. Go to the subdirectory vbcc/machines/amiga.
  171.  
  172.     2. If you have the Amiga OS-includes copy them into the include
  173.        directory.
  174.  
  175.     3. Execute the script init_vbcc.
  176.  
  177.     4. If you compile larger projects it may be necessary to increase
  178.        the stack further.
  179.  
  180.     If you use vbcc frequently it is probably a good idea to add those
  181.     commands to your user-startup, shell-startup or similar.
  182.  
  183.     Now you should be able to use vbcc. E.g. if you want to compile and
  184.     link the program hello.c you can type
  185.  
  186.         vc +ppc hello.c
  187.  
  188.     This will compile and link the file hello.c and create the executable
  189.     a.out in the current directory. (If you executed PPCInstall or the
  190.     ELFLoadSegPatch you can run the executable just like an 68k binary.
  191.     Otherwise you can run the executable using ppcrun with the syntax
  192.     ppcrun <program> <arguments>.)
  193.  
  194.         vc +ppc hello.c -o hello
  195.  
  196.     will do the same, but the created executable will be called hello.
  197.  
  198.         vc +ppc -c t1.c t2.c
  199.  
  200.     will compile t1.c and t2.c without linking, creating the object files
  201.     t1.o and t2.o.
  202.  
  203.         vc +ppc t1.o t2.o -o tt
  204.  
  205.     will link them together and create the executable tt.
  206.  
  207.     If your program uses floating point add -lm to the commandline
  208.     to link with the math-library, e.g.:
  209.  
  210.         vc +ppc calc.c -o calc -lm
  211.  
  212.     IMPORTANT: If your program uses AmigaOS-functions you have to specify
  213.     the option -amiga-align, e.g.
  214.  
  215.         vc +ppc -amiga-align myOsPrg.c
  216.  
  217.     There is also an extra.lib which includes a few functions that are
  218.     no standard ANSI functions but some people seem to regard them as
  219.     standard functions. If you use one of these add -lextra to the
  220.     commandline and read:
  221.  
  222.         vbcc/machines/amiga/doc/extralibppc.doc
  223.  
  224.     For further information read the files:
  225.  
  226.         vbcc/doc/vbcc.doc
  227.         vbcc/doc/vc.doc
  228.         vbcc/doc/vbccppc.doc
  229.         vbcc/machines/amiga/doc/vclibppc.doc
  230.  
  231.  
  232. SUPPORT FOR OTHER TARGETS
  233.  
  234.     This release of vbcc is able to generate code for 68k, PPC/ELF
  235.     and PPC/WarpOS. If you have installed other backends you can
  236.     choose the target by specifying another config file with the
  237.     '+'-option (e.g. +ppc).
  238.  
  239.     For further details see the corresponding docs for this target.
  240.  
  241.  
  242. CONFIGURATION
  243.  
  244.     The frontend searches for a file vc.config in ENV: and vbcc: to read
  245.     preferences. The provided sample vc.config should be usable and does
  246.     not have to be changed but you can add something to suit your personal
  247.     preferences - read
  248.  
  249.         vbcc/doc/vc.doc
  250.  
  251.     to find out more.
  252.  
  253.  
  254. MESSAGE BROWSER
  255.  
  256.     If you start the message browser with
  257.  
  258.         run vbrowse
  259.  
  260.     it will open a window with a listview gadget. If you have a pipe
  261.     command installed you can now invoke vc via tovbr, e.g.
  262.  
  263.         tovbr vc hello.c
  264.  
  265.     and any output from vc will be displayed in the window of vbrowse
  266.     rather than in the shell. It might be convenient to make an alias like
  267.  
  268.         alias vb tovbr vc
  269.  
  270.     so that invoking vb will automatically display the output in the browser.
  271.  
  272.     If there is an error/warning-message in the browser you can invoke a
  273.     configurable command by double-clicking on the message.
  274.  
  275.     Double-clicking on the quoted line will invoke GoldEd (if you have it
  276.     installed) by default, load the file that caused the error and the cursor
  277.     will be placed on this line in the default configuration. If you use
  278.     another editor or want to change this behaviour have a look at
  279.     vbcc/machines/amiga/doc/vbrowse.doc.
  280.  
  281.     Double-clicking on the error-line (the one below the quoted line) will
  282.     invoke the command showerr that will open the VBCCMessages.guide and
  283.     display a more detailed description of the error (if there is one in
  284.     the guide - there are not yet descriptions for all messages).
  285.  
  286.     Read vbcc/machines/amiga/vbrowse.doc for further information.
  287.  
  288.  
  289. CONTENTS
  290.  
  291.     This archive contains (among others) the following files and directories:
  292.  
  293.     vbcc/
  294.  
  295.             The main directory. The source files for the compiler and the
  296.             builtin preprocessor by Thorsten Schaaps are here.
  297.  
  298.     vbcc/doc/
  299.  
  300.             Host independant documentation for the compiler is in this dir.
  301.  
  302.     vbcc/doc/History
  303.  
  304.             Changes in since earlier versions of the compiler.
  305.  
  306.     vbcc/doc/vbcc.doc
  307.  
  308.             Documentation for the target-independant part of the compiler.
  309.  
  310.     vbcc/doc/vbcc.faq
  311.  
  312.             Frequently asked questions about vbcc.
  313.  
  314.     vbcc/doc/errors.doc
  315.  
  316.             A list of all error/warning-messages from the compiler -
  317.             sometimes with more detailed descriptions.
  318.  
  319.     vbcc/doc/vbccppc.doc
  320.  
  321.             Documentation for the PPC code generator.
  322.  
  323.     vbcc/doc/vc.doc
  324.  
  325.             Documentation for the compiler-frontend.
  326.  
  327.     vbcc/doc/pasm.doc
  328.  
  329.             Documentation for the assembler by Frank Wille.
  330.  
  331.     vbcc/doc/vlink.doc
  332.  
  333.             Documentation for the linker by Frank Wille.
  334.  
  335.     vbcc/doc/vcpp.doc
  336.  
  337.             Some short comments regarding the preprocessor from the
  338.             lcc-distribution. Read the copyright-notice.
  339.  
  340.     vbcc/doc/building.doc
  341.  
  342.             Documentation on building vbcc.
  343.  
  344.     vbcc/bin/
  345.  
  346.             The directory containing binaries of preprocessor, compiler and
  347.             frontend. Additional binaries may be in machines/xyz/bin/.
  348.  
  349.     vbcc/bin/vbccm68k
  350.  
  351.             The native C compiler for m68k.
  352.  
  353.     vbcc/bin/vbccppc
  354.  
  355.             The C cross-compiler for PPC. Running on m68k.
  356.  
  357.     vbcc/bin/vbccm68k_ppc
  358.  
  359.             The C cross-compiler for m68k. Running on PPC/ELF. (optional)
  360.  
  361.     vbcc/bin/vbccppc_ppc
  362.  
  363.             The native C compiler for PPC/ELF. (optional)
  364.  
  365.     vbcc/bin/vbccm68k_wos
  366.  
  367.             The C cross-compiler for m68k. Running on PPC/WOS. (optional)
  368.  
  369.     vbcc/bin/vbccppc_wos
  370.  
  371.             The native C compiler for PPC/WOS. (optional)
  372.  
  373.     vbcc/bin/vc
  374.  
  375.             The compiler-frontend.
  376.  
  377.     vbcc/bin/pasm
  378.  
  379.             The assembler by Frank Wille.
  380.  
  381.     vbcc/bin/vlink
  382.  
  383.             The linker by Frank Wille.
  384.  
  385.     vbcc/bin/ar
  386.  
  387.             The archiver by Frank Wille.
  388.  
  389.     vbcc/bin/vcpp
  390.  
  391.             The preprocessor from the lcc-distribution (by Dennis Ritchie).
  392.  
  393.     vbcc/machines/amiga/doc/
  394.  
  395.             This contains documentation for the Amiga specific parts.
  396.  
  397.     vbcc/machines/amiga/doc/extralibppc.doc
  398.  
  399.             Documentation for extra.lib.
  400.  
  401.     vbcc/machines/amiga/doc/VBCCMessages.guide
  402.  
  403.             The vbcc/doc/errors.doc in Amigaguide-format (done by Walter
  404.             Doerwald).
  405.  
  406.     vbcc/machines/amiga/doc/vclibmppc.doc
  407.  
  408.             Documentation for the Amiga-C-library.
  409.  
  410.     vbcc/machines/amiga/doc/vbrowse.doc
  411.  
  412.             Documentation on the message browser and several connected tools.
  413.  
  414.     vbcc/machines/amiga/init_vbcc
  415.  
  416.             A sample script to do the necessary assigns etc. to use vbcc.
  417.  
  418.     vbcc/machines/amiga/include
  419.  
  420.             Here you can install the OS-includes.
  421.  
  422.     vbcc/machines/amiga/bin/
  423.  
  424.             This directory contains all Amiga-specific executables.
  425.  
  426.     vbcc/machines/amiga/bin/vbrowse
  427.     vbcc/machines/amiga/bin/vsend
  428.     vbcc/machines/amiga/bin/tovbr
  429.     vbcc/machines/amiga/bin/showerr
  430.  
  431.             The message browser and some tools.
  432.  
  433.     vbcc/machines/amigappc/include
  434.  
  435.             This directory contains the standard-ANSI-includes for libvc.a.
  436.  
  437.     vbcc/machines/amigappc/bin/
  438.  
  439.             This directory contains AmigaPPC-specific executables.
  440.  
  441.     vbcc/machines/amiga/bin/ppcrun
  442.  
  443.             Program used to start PPC-ELF-executables.
  444.  
  445.     vbcc/machines/amiga/bin/fd2libPPC
  446.  
  447.             fd2lib generates stubs for shared libraries and must be used to
  448.             rebuilt libvc.a or if you want to use any custom shared-library.
  449.  
  450.     vbcc/machines/amigappc/lib/
  451.  
  452.             This directory contains the link-libraries and startup-codes.
  453.  
  454.     vbcc/machines/amigappc/lib/startup.o
  455.  
  456.             The standard startup-code for libvc.a.
  457.  
  458.     vbcc/machines/amigappc/lib/minstart.o
  459.  
  460.             Minimal startup-code.
  461.  
  462.     vbcc/machines/amigappc/lib/libvc.a
  463.  
  464.             The standard C-library.
  465.  
  466.     vbcc/machines/amigappc/lib/libvcs.a
  467.  
  468.             The standard C-library (small data).
  469.  
  470.     vbcc/machines/amigappc/lib/libm.a
  471.  
  472.             Math-library.
  473.  
  474.     vbcc/machines/amigappc/lib/libamiga.a
  475.  
  476.             Replacement for the standard amiga.lib.
  477.  
  478.     vbcc/machines/amigappc/lib/libamigas.a
  479.  
  480.             Replacement for the standard amiga.lib (small data).
  481.  
  482.     vbcc/machines/amigappc/lib/libauto.a
  483.  
  484.             Library for automatic opening of system libraries.
  485.  
  486.     vbcc/machines/amigappc/lib/libautos.a
  487.  
  488.             Library for automatic opening of system libraries (small data).
  489.  
  490.     vbcc/machines/amigappc/lib/libextra.a
  491.  
  492.             Very small library containing a few functions some people want.
  493.  
  494.     vbcc/machines/amigappc/lib/libextras.a
  495.  
  496.             Very small library containing a few functions some people want.
  497.  
  498.  
  499.  
  500. BUGREPORTS/COMMENTS
  501.  
  502.     If you think vbcc generates bad code, throws enforcer hits, crashes,
  503.     seems to be not ANSI-compliant etc. and the problem is not mentioned
  504.     anywhere in this docs as known problem, please send a mail with your
  505.     system configuration, the vbcc version, the command line you used, the
  506.     source that caused the problem and a brief description of the problem to
  507.  
  508.         volker@vb.franken.de
  509.  
  510.     Also if you find problems with the includes, the libraries or you have
  511.     suggestions, dislikes etc. send me a mail.
  512.     Corrections, improvements etc. of the manuals are appreciated, too.
  513.  
  514.  
  515.  
  516. Volker Barthelmann                                      volker@vb.franken.de
  517.  
  518.